home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / libs / pdcurs21 / doc / intro.man next >
Text File  |  1992-11-16  |  7KB  |  193 lines
  1. /*man-start*********************************************************************
  2.  
  3.         Introduction to XSI Curses Interface
  4.  
  5. The X/Open Group has identified a strong need for a generic terminal
  6. interface for applications that wish to be independent of terminal
  7. hardware and connection method.
  8.  
  9. This interface should allow the attachment of character and
  10. block-oriented terminals.  Furthermore, it should not put any
  11. constraints on how the terminals are attached (e.g., Local Area
  12. Networks, PADs on X.25, etc.). 
  13.  
  14. The curses library interfaces provides the user with a method of
  15. updating screens with reasonable optimisation. 
  16.  
  17. The X/Open group has found it impossible to define a totally portable
  18. set of curses interface routines that cover asynchronous, networked,
  19. and synchronous terminals.  The functions are oriented towards locally
  20. connected asynchronous terminals.  For such terminals, applications
  21. conforming to this interface are portable.  The interface routines
  22. curses may, however, also be used with synchronous and networked
  23. terminals, provided the restrictions below are considered. 
  24.  
  25. These functions have been included been included in the X/Open
  26. definition in the "optional" category.  This means that although they
  27. are likely to appear on many X/Open compliant systems, they are not
  28. guaranteed to be on all systems.  Where they are supported, they will
  29. conform to the given definition. 
  30.  
  31.  
  32. ----------------------------------------------------------------------
  33.  
  34.         Synchronous and Networked Asynchronous Terminals
  35.  
  36. These notes indicate to the application writer some considerations to
  37. be borne in mind when driving synchronous, networked asynchronous
  38. (NWA) or non-standard directly connected asynchronous terminals.
  39.  
  40. Such terminals are often used in a mainframe environment and
  41. communicatie to the host in block mode.  That is, the user types
  42. characters at the terminal then presses a special key to initiate
  43. transmission of the characters to the host. 
  44.  
  45. Frequently, although it may be possible to send arbitrary sized blocks
  46. to the host, it may not be possible or desireable to cause a character
  47. to be transmitted with only a single keystroke. 
  48.  
  49. This can cause severe problems to an application wishing to make use
  50. of single character input. 
  51.  
  52.  
  53.  
  54. OUTPUT
  55.  
  56. The curses package can be used in the normal way for all operations
  57. pertaining to output to the terminal, with the possible exception that
  58. on some terminals the refresh() routine may have to redraw the entire
  59. screen contents in order to perform any update.
  60.  
  61. If it is additionally necessary to clear the screen before each such
  62. operation, the result could be unacceptable. 
  63.  
  64.  
  65. INPUT
  66.  
  67. Because of the nature of operation of synchronous (block-mode) and NWA
  68. terminals, it may not be possible to support all or any of the curses
  69. input functions.  In particular, the following points should be noted:
  70.  
  71. * Single-character input may not be possible.  It may be necessary to
  72.   press a special key to cause all characters typed at the terminal to
  73.   be transmitted to the host. 
  74.  
  75. * It may not be possibel to disable echo.  Character echo may be performed
  76.   directly by the terminal.  On terminals that behave this way, any curses
  77.   application that performs input should be aware that any characters
  78.   type will appear on the screen wherever the cursor is positioned.
  79.   This may not necessarily correspond to the position of the cursor in
  80.   the window.
  81.  
  82.  
  83. ----------------------------------------------------------------------
  84.  
  85.         Data Types and the <curses.h> Header
  86.  
  87. The data types supported by curses are described in this section.
  88.  
  89. As the library supports a procedural interface to the data types,
  90. actual structure contents are not described.  All curses data are
  91. manipulated using the routines provided. 
  92.  
  93.  
  94. THE <curses.h> HEADER
  95.  
  96. The <curses.h> header defines various constants and declares the data types
  97. that are available to the application.
  98.  
  99.  
  100. DATA TYPES
  101.  
  102. The following data types are declared:
  103.  
  104.     WINDOW*        pointer to screen representation
  105.     SCREEN*        pointer to terminal descriptor
  106.     bool        boolean data type
  107.     chtype        representation of a character in a window
  108.  
  109. The actual WINDOW and SCREEN objects used to store information are
  110. created by the corresponding routiens and a pointer to them is
  111. provided.  All manipulation is through that pointer. 
  112.  
  113.  
  114. CONSTANTS
  115.  
  116. The following constants are defined. 
  117.  
  118.  
  119. GENERAL
  120.  
  121.     COLS        number of columns on terminal screen
  122.     ERR        value returned on error condition
  123.     FALSE        boolean false value
  124.     LINES        number of lines on terminal screen
  125.     OK        value returned on successful completion
  126.     NULL        zero pointer value
  127.     TRUE        boolean true value
  128.  
  129. VIDEO ATTRIBUTES
  130.  
  131.     A_BLINK        blinking
  132.     A_BOLD        extra bright or bold
  133.     A_DIM        half bright
  134.     A_REVERSE    reverse video
  135.     A_STANDOUT    terminal's best highlighting mode
  136.     A_UNDERLINE    underlining
  137.     A_ATTRIBUTES    bit-mask to extract attributes
  138.     A_CHARTEXT    bit-mask to extract a character
  139.  
  140. Normally, attributres are a property of the character. 
  141.  
  142.  
  143. INPUT VALUES
  144.  
  145. The following constants might be returned by getch() if keypad() has
  146. been enabled.  Note that not all of these may be supported on a
  147. particular terminal if the terminal does not transmit a unique code
  148. when the key is pressed or the definition for the key is not present
  149. in the underlying table of terminal capabilities. 
  150.  
  151.     KEY_BREAK    break key
  152.     KEY_DOWN    the four arrow keys
  153.     KEY_UP
  154.     KEY_LEFT
  155.     KEY_RIGHT
  156.     KEY_HOME    home key (upward+left arrow)
  157.     KEY_BACKSPACE    backspace
  158.     KEY_F0        function keys; space for 64 keys is reserved
  159.     KEY_F(n)    (KEY_F0+(n))
  160.     KEY_DL        delete line
  161.     KEY_IL        insert line
  162.     KEY_DC        delete character
  163.     KEY_IC        insert character
  164.     KEY_EIC        exit insert character mode
  165.     KEY_CLEAR    clear screen
  166.     KEY_EOS        clear to end of screen
  167.     KEY_EOL        clear to end of line
  168.     KEY_SF        scroll 1 line forwards
  169.     KEY_SR        scroll 1 line backwards (reverse)
  170.     KEY_NPAGE    next page
  171.     KEY_PPAGE    previous page
  172.     KEY_STAB    set tab
  173.     KEY_CTAB    clear tab
  174.     KEY_CATAB    clear all tabs
  175.     KEY_ENTER    enter or send
  176.     KEY_SRESET    soft (partial) reset
  177.     KEY_RESET    reset or hard reset
  178.     KEY_PRINT    print or copy
  179.     KEY_LL        home down or bottom (lower left)
  180.     KEY_A1        upper left of virtual keypad
  181.     KEY_A3        upper right of virtual keypad
  182.     KEY_B2        centre of virtual keypad
  183.     KEY_C1        lower left of virtual keypad
  184.     KEY_C3        lower right of virtual keypad
  185.  
  186. The virtual keypad is arranged like this:
  187.  
  188.     A1    up    A3
  189.     left    B2    right
  190.     C1    down    C3
  191.  
  192. **man-end**********************************************************************/
  193.